IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / Vk / VkApp.z / VkApp

Wrap

Text File | 2001-04-17 | 58.7 KB | 1,387 lines

VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) NNNNAAAAMMMMEEEE VkApp - Class used by all ViewKit applications to handle initialization IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM VkComponent : VkCallbackObject HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE #include <Vk/VkApp.h> PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss VkApp(char *appClassName, int *arg_c, char **arg_v, XrmOptionDescRec *optionList = NULL, int sizeOfOptionList = 0 ) VkApp(char *appClassName, int *arg_c, char **arg_v, ArgList argList, Cardinal argCount, void (*preRealizeFunction)(Widget w), XrmOptionDescRec *optionList, int sizeOfOptionList) VVVVeeeerrrrssssiiiioooonnnn IIIInnnnffffoooorrrrmmmmaaaattttiiiioooonnnn static const int ViewKitMajorRelease static const int ViewKitMinorRelease static const char ViewKitReleaseString[] void setVersionString(const char *str) const char *versionString() void setAboutDialog(VkDialogManager *aboutDialog) void setStartupDialog(VkDialogManager *startupDialog) RRRRuuuunnnnttttiiiimmmmeeee IIIInnnntttteeeerrrraaaaccccttttiiiioooonnnn virtual void run() void run(Boolean(*appEventHandler)(XEvent &)) void runOneEvent(Boolean(*appEventHandler)(XEvent &) = NULL) void run_first() virtual void handlePendingEvents() void handlePendingEvents(Boolean(*appEventHandler)(XEvent &)) XtInputMask handleOnePendingEvent(Boolean(*appEventHandler)(XEvent &) = NULL) virtual void handleRawEvent(XEvent *event) virtual void quitYourself() virtual void terminate(int status = 0) PPPPaaaaggggeeee 1111 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) OOOOppppeeeerrrraaaattttiiiioooonnnnssss oooonnnn AAAApppppppplllliiiiccccaaaattttiiiioooonnnn WWWWiiiinnnnddddoooowwwwssss void setMainWindow(VkSimpleWindow *win) virtual void raise() virtual void lower() virtual void iconify() virtual void open() virtual void show() virtual void hide() void startupIconified(Boolean flag) AAAApppppppplllliiiiccccaaaattttiiiioooonnnn CCCCuuuurrrrssssoooorrrr CCCCoooonnnnttttrrrroooollll virtual Cursor busyCursor() virtual Cursor normalCursor() void setNormalCursor(Cursor c) void setBusyCursor(Cursor c) void setBusyCursor(VkCursorList *cl) void showCursor(Cursor c) SSSSuuuuppppppppoooorrrrtttt ffffoooorrrr BBBBuuuussssyyyy SSSSttttaaaatttteeeessss virtual void busy(const char *msg = NULL, VkSimpleWindow *parent = NULL) virtual void veryBusy(const char *msg = NULL, VkSimpleWindow *parent = NULL) virtual void notBusy() void setBusyDialog(VkBusyDialog *d) virtual void progressing(const char *msg = NULL); CCCCoooonnnnvvvveeeennnniiiieeeennnntttt AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss XtAppContext appContext() const char *name() const Display *display() const char **argv() const char *argv(int index) const int argc() const char *applicationClassName() const VkSimpleWindow *mainWindow() const void setFallbacks(char **fallbacks) char *shellGeometry() const Boolean startupIconified() const virtual const char *className() const VkApp *theApplication VVVViiiissssuuuuaaaallll CCCCoooonnnnttttrrrroooollll static void useOverlayApps(const Boolean flag) PPPPaaaaggggeeee 2222 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) HHHHeeeellllpppp ssssyyyysssstttteeeemmmm int helpInit(char *client, char *sep); int helpMsg(char *key, char *book, char *userData); int helpIndexMsg(char *key, char *book); static const char *const helpInitCallback; static const char *const helpMsgCallback; static const char *const helpIndexMsgCallback; void useSGIHelp(); static void sgiHelpInit(VkCallbackObject* caller, void* clientData, void* callData); static void sgiHelpMsg(VkCallbackObject* caller, void* clientData, void* callData); static void sgiHelpIndexMsg(VkCallbackObject* caller, void* clientData, void* callData); PPPPRRRROOOOTTTTEEEECCCCTTTTEEEEDDDD PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY int parseCommandLine(XrmOptionDescRec *opt, Cardinal numOptions) VkComponentList _winList virtual void afterRealizeHook() CCCCOOOOMMMMMMMMAAAANNNNDDDD LLLLIIIINNNNEEEE OOOOPPPPTTTTIIIIOOOONNNNSSSS AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD WWWWIIIITTTTHHHH TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS -_s_c_h_e_m_e Sets the scheme for the application's resources. -_u_s_e_O_v_e_r_l_a_y_A_p_p_s If true, this resource causes the entire application to use the deepest available overlay planes. -_u_s_e_O_v_e_r_l_a_y_D_i_a_l_o_g_s If true, this resource causes all dialogs to use the deepest available overlay planes. -_u_s_e_O_v_e_r_l_a_y_M_e_n_u_s If true, this resource causes all menus to use the deepest available overlay planes. XXXX RRRREEEESSSSOOOOUUUURRRRCCCCEEEESSSS AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD WWWWIIIITTTTHHHH TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS _b_u_s_y_C_u_r_s_o_r_F_o_r_e_g_r_o_u_n_d The foreground color used by the busy cursor. PPPPaaaaggggeeee 3333 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) _b_u_s_y_C_u_r_s_o_r_B_a_c_k_g_r_o_u_n_d The background color used by the busy cursor. _i_c_o_n_i_c If true, this resource causes the entire application to startup iconified. _n_o_r_m_a_l_C_u_r_s_o_r_F_o_r_e_g_r_o_u_n_d The foreground color used by the normal cursor. _n_o_r_m_a_l_C_u_r_s_o_r_B_a_c_k_g_r_o_u_n_d The background color used by the normal cursor. _s_i_l_e_n_c_e_W_a_r_n_i_n_g_s If True, an application will install error and warning handlers that effectively hide all Xt warnings. Some of these messages are unavoidable, and this resource can be set before a product is shipped. _u_s_e_O_v_e_r_l_a_y_A_p_p_s This is equivalent to the command-line switch -_u_s_e_O_v_e_r_l_a_y_A_p_p_s. _u_s_e_O_v_e_r_l_a_y_D_i_a_l_o_g_s This is equivalent to the command-line switch -_u_s_e_O_v_e_r_l_a_y_D_i_a_l_o_g_s. _u_s_e_O_v_e_r_l_a_y_M_e_n_u_s This is equivalent to the command-line switch -_u_s_e_O_v_e_r_l_a_y_M_e_n_u_s. XXXX DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG RRRREEEESSSSOOOOUUUURRRRCCCCEEEESSSS AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD WWWWIIIITTTTHHHH TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS There are some resources that are only available in the debugging versions of the library. Non-debugging versions of the library simply ignore them. _d_e_b_u_g_R_e_s_o_u_r_c_e_s If this resource is set to true, the application will save the contents of its resource database to /usr/tmp/resources.db. _d_e_b_u_g_X_t_M_o_d_e If true, the application will core dump when any X or Xt warning or error occurs. _p_r_i_n_t_E_v_e_n_t if non-zero, ViewKit will print information about each event to stderr. Currently (6/96) the name of each event, the name of the widget that got the event, and the widget's classname are printed. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN VkApp provides various central facilities required by all ViewKit applications. All applications must create a single instance of VkApp or a derived class. PPPPaaaaggggeeee 4444 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) The following constructor is the normal one. Most applications will have no reason to use any other. VkApp(char *appClassName, int *arg_c, char **arg_v, XrmOptionDescRec *optionList = NULL, int sizeOfOptionList = 0); The following constructor is rarely needed. It is used when an application must set creation-time resources on the invisible top-level shell widget that VkApp creates. One use of it is for an application that runs entirely in a non-default visual, and also has Motif drag and drop enabled. Such an application should use this constructor to set the visual attributes for the shell that the VkApp constructor creates, so that they match those used for the rest of the application. Setting the visual attributes this way allows the application to have all of its shells in a single non-default visual. (As of 6/96, if an application does not ensure that its visuals match, Motif drag and drop will core dump. There are non-obvious work-arounds, and a genuine multi-visual application must still use them.) VkApp(char *appClassName, int *arg_c, char **arg_v, ArgList argList, Cardinal argCount, void (*preRealizeFunction)(Widget w), XrmOptionDescRec *optionList, int sizeOfOptionList); Upon instantiation, VkApp calls various Xt functions to connect to the X server and initialize the Xt Intrinsics. ViewKit applications should _n_o_t call _X_t_A_p_p_I_n_i_t_i_a_l_i_z_e() or other similar Xt initialization functions directly. VkApp uses the application-context style Xt functions throughout, and wherever applicable, ViewKit applications must use the app-context versions of all Xt functions. The simplest use of the VkApp class is to create an instance, create other windows as needed (see VkSimpleWindow), and call _V_k_A_p_p::_r_u_n(), as seen in the following example program. #include <Vk/VkApp.h> #include <Vk/VkSimpleWindow.h> void main ( int argc, char **argv ) { PPPPaaaaggggeeee 5555 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) VkApp *app = new VkApp("Application", &argc, argv); VkSimpleWindow *win = new VkSimpleWindow("window"); win->show(); app->run(); } An application's instance of VkApp can be referenced as _t_h_e_A_p_p_l_i_c_a_t_i_o_n throughout an application, in any file that includes VkApp.h. This allows easy use of various VkApp facilities, such as the _b_u_s_y() facility, and easy access to the X Display pointer, the Xt application context, and so on. DDDDeeeerrrriiiivvvviiiinnnngggg SSSSuuuubbbbccccllllaaaasssssssseeeessss It is often useful to create subclasses of VkApp to support additional application-wide services. One typical use of a derived class is to parse additional command-line arguments. For example, the following simple example specifies a -_v_e_r_b_o_s_e command-line argument, using an _X_r_m_O_p_t_i_o_n_D_e_s_c_R_e_c. This array is passed to the protected member function _p_a_r_s_e_C_o_m_m_a_n_d_L_i_n_e() to extract the flag, if it exists. The value of all recovered options are placed in the application's resource database, where they can be retrieved as needed. Notice that _p_a_r_s_e_C_o_m_m_a_n_d_L_i_n_e() returns an updated value of argc which _m_u_s_t be used to update the value of argc as passed in by the calling application. Failure to do so will cause problems for applications that reference this value after instantiating a VkApp object. (Applications can avoid any difficulties by not referencing args directly, and using _t_h_e_A_p_p_l_i_c_a_t_i_o_n->_a_r_g_c() instead.) #include <Vk/VkApp.h> class App : public VkApp { private: // Declare a description of the command line options static XrmOptionDescRec _cmdLineOptions[]; public: App(char *appClassName, int *arg_c, char **arg_v, XrmOptionDescRec *optionList = NULL, int sizeOfOptionList = 0); }; // Describe the command line options PPPPaaaaggggeeee 6666 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) XrmOptionDescRec App::_cmdLineOptions[] = { { "-verbose", "*verbose", XrmoptionNoArg, "TRUE", }, }; // Constructor App::MyApp(char *appClassName, int *arg_c, char **arg_v, XrmOptionDescRec *optionList, int sizeOfOptionList) : VkApp(appClassName, arg_c, arg_v, optionList, sizeOfOptionList) { // Parse the command line *arg_c = parseCommandLine(_cmdLineOptions, XtNumber(_cmdLineOptions)); } Derived classes may also need access to the windows currently used in an application. The _winList member provides access to a list of windows, in the form of a VkComponentList object (see VkComponentList(3x)). VVVVIIIIEEEEWWWWKKKKIIIITTTT VVVVEEEERRRRSSSSIIIIOOOONNNNSSSS The ViewKit supports several constants that can be used to identify the current ViewKit release. These are: VVVViiiieeeewwwwKKKKiiiittttMMMMaaaajjjjoooorrrrRRRReeeelllleeeeaaaasssseeee;;;; static const int ViewKitMajorRelease; This integer value identifies the major release of the ViewKit. For example, in a 1.2 release, this value would be "1". Should it prove necessary to use conditional statements in your code to handle different versions of the library, this value can be useful. VVVViiiieeeewwwwKKKKiiiittttMMMMiiiinnnnoooorrrrRRRReeeelllleeeeaaaasssseeee;;;; static const int ViewKitMinorRelease; This integer value identifies the current minor release of the ViewKit. For example, in a 1.2 release, this value would be "2". Should it prove necessary to use conditional statements in your code PPPPaaaaggggeeee 7777 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) to handle different versions of the library, this value can be useful. VVVViiiieeeewwwwKKKKiiiittttRRRReeeelllleeeeaaaasssseeeeSSSSttttrrrriiiinnnngggg static const char ViewKitReleaseString[]; This string contains the complete major and minor release information on the ViewKit. You can identify the version of the ViewKit an application is compiled with by running: strings program | grep "ViewKit Release" FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS VVVVkkkkAAAApppppppp(((()))) VkApp(char *appClassName, int *arg_c, char **arg_v, XrmOptionDescRec *optionList = NULL, int sizeOfOptionList = 0) The VkApp constructor initializes the Xt Intrinsics by calling _X_t_T_o_o_l_k_i_t_I_n_i_t_i_a_l_i_z_e(), _X_t_C_r_e_a_t_e_A_p_p_l_i_c_a_t_i_o_n_C_o_n_t_e_x_t() and _X_t_O_p_e_n_D_i_s_p_l_a_y(). The constructor also creates a shell to serve as a parent for all other main windows. The ViewKit supports the multi- shell architecture described in the book "X Window System Toolkit", Asente and Swick, 1990. All other windows are created as popup children of the shell created by VkApp, which is never visible. The VkApp constructor also installs various error handlers and retrieves the application resources recognized by VkApp. The first argument indicates the class name of the application, which is used to load application resources. The second and third arguments must be a pointer to argc and the application's argv array. These arguments are passed to _X_t_O_p_e_n_D_i_s_p_l_a_y() and the recognized arguments are removed. The following constructor is rarely needed. It is only used when an application must set creation-time resources on the invisible top-level shell widget that VkApp creates. This constructor operates just like the (shorter) more common one (above), except that it provides control over the resources used when the application's top level shell is created. The motivation for this is that without it you cannot have a single- visual application that was not in the default visual. VkApp(char *appClassName, int *arg_c, char **arg_v, ArgList argList, Cardinal argCount, PPPPaaaaggggeeee 8888 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) void (*preRealizeFunction)(Widget w), XrmOptionDescRec *optionList, int sizeOfOptionList); One use of this constructor is for an application that runs entirely in a non-default visual, and also has Motif drag and drop enabled. Such an application should use this constructor to set the visual attributes for the shell that the VkApp constructor creates, so that they match those used for the rest of the application. Setting the visual attributes this way allows the application to have all of its shells in a single non-default visual. (As of 6/96, if an application does not ensure that its visuals match, Motif drag and drop will core dump. There are non-obvious work-arounds, and a genuine multi-visual application must still use them.) +o Any resource that can be passed on the _a_r_g_L_i_s_t, such as default font list, should be passed in that way. +o Visual information cannot be known until after the display is opened, and so cannot be passed in on the _a_r_g_L_i_s_t. +o _p_r_e_R_e_a_l_i_z_e_F_u_n_c_t_i_o_n(_w) will be called with the baseWidget (i.e the shell). It will be called after widget creation, but before the widget is realized. At that time, the application can find the visual information it needs, and do an _X_t_S_e_t_V_a_l_u_e_s() call. The manual not withstanding, since the widget has not yet been realized, this is OK - provided that the call sets _a_l_l _v_i_s_u_a_l _r_e_s_o_u_r_c_e_s consistently. sssseeeettttAAAAbbbboooouuuuttttDDDDiiiiaaaalllloooogggg void setAboutDialog(VkDialogManager *dialog); This function allows applications to replace the dialog displayed when the user asks for help on "Product Info". The default behavior of this help item is to display a VkInformationDialog that reports the name and version information for this application (See setVersionInfo, and VkInformationDialog). Applications that wish to customize the dialog that appears in this case can install any subclass of VkDialogManager using this function. The new dialog will be posted with a string that identifies the name of the application and the version, but otherwise the content of the dialog is up to the application. (See VkDialogManager and VkGenericDialog for more information on dialogs.) +o The string "Application Name:" in the default popup dialog can be localized by adding a resource, vkAppNameL10NString, with a translated string to the application's app-defaults file. For example; PPPPaaaaggggeeee 9999 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) *vkAppNameL10NString: Application Name: sssseeeettttVVVVeeeerrrrssssiiiioooonnnnSSSSttttrrrriiiinnnngggg void setVersionString(const char *str); This function specifies a string to be used as the version of an application based on the ViewKit. This string appears by default in the "Product Info" dialog. vvvveeeerrrrssssiiiioooonnnnSSSSttttrrrriiiinnnngggg const char *versionString(); This function retrieves the currently installed version string. rrrruuuunnnn virtual void run(); This function should be called instead of _X_t_A_p_p_M_a_i_n_L_o_o_p() in ViewKit programs. _r_u_n() calls _r_u_n__f_i_r_s_t() to do some internal initialization, and then enters a custom main loop that dispatches application events, raw X events, and normal Xt events. (see _h_a_n_d_l_e_R_a_w_E_v_e_n_t().) void run(Boolean(*appEventHandler)(XEvent &)) This is the easiest way to customize ViewKit's X event loop. This entry allows an application to customize the event loop without taking responsibility for the entire event loop. For each event, the application can either supplement or replace the main event loop handling. Each time through the event loop, before doing any event processing of its own, _r_u_n() calls _a_p_p_E_v_e_n_t_H_a_n_d_l_e_r() with the event. If _a_p_p_E_v_e_n_t_H_a_n_d_l_e_r() has completely handled the event, it returns TRUE and no further handling of that event occurs. If ViewKit handling of that event is still needed, then _a_p_p_E_v_e_n_t_H_a_n_d_l_e_r() must return FALSE. void run_first() _r_u_n__f_i_r_s_t() is called by _r_u_n(). Any application that overrides _r_u_n() must ensure that _r_u_n__f_i_r_s_t() gets called. See OOOOvvvveeeerrrrrrrriiiiddddiiiinnnngggg VVVVkkkkAAAApppppppp::::::::rrrruuuunnnn(((()))), below, for more information. PPPPaaaaggggeeee 11110000 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) void runOneEvent(Boolean(*appEventHandler)(XEvent &) = NULL) _r_u_n_O_n_e_E_v_e_n_t() is the event handling function called by _r_u_n(). It does whatever things ViewKit needs beyond the standard Xt event handling. Any application that overrides _r_u_n() must ensure that some ViewKit event handling function gets called. See OOOOvvvveeeerrrrrrrriiiiddddiiiinnnngggg VVVVkkkkAAAApppppppp::::::::rrrruuuunnnn(((()))), below, for more information. hhhhaaaannnnddddlllleeeePPPPeeeennnnddddiiiinnnnggggEEEEvvvveeeennnnttttssss virtual void handlePendingEvents(); _h_a_n_d_l_e_P_e_n_d_i_n_g_E_v_e_n_t_s() retrieves and dispatches all X11 events, timers, and alternate input. It does not block -- it returns when there is nothing pending. It does not call any workproc's. void VkApp::handlePendingEvents(Boolean(*appEventHandler)(XEvent &)) This version is exactly the same as _h_a_n_d_l_e_P_e_n_d_i_n_g_E_v_e_n_t_s(), above, except that it allows an application's event handler to also see each event. See _r_u_n_O_n_e_E_v_e_n_t(_B_o_o_l_e_a_n(*_a_p_p_E_v_e_n_t_H_a_n_d_l_e_r)(_X_E_v_e_n_t &) = _N_U_L_L), above, for more information. XtInputMask VkApp::handleOnePendingEvent( Boolean(*appEventHandler)(XEvent &) = NULL) _h_a_n_d_l_e_O_n_e_P_e_n_d_i_n_g_E_v_e_n_t() returns after handling a single event, or immediately if there are no events. The return value is the mask returned by _X_t_A_p_p_P_e_n_d_i_n_g(), which will be zero if there are no pending events. The purpose of this routine is to permit construction of non-blocking event loops that do something before (and/or after) each event. OOOOvvvveeeerrrrrrrriiiiddddiiiinnnngggg VVVVkkkkAAAApppppppp::::::::rrrruuuunnnn(((()))) _r_u_n() consists of: void VkApp::run() { run_first(); while (True) { runOneEvent((Boolean(*)(XEvent &)) NULL); } } PPPPaaaaggggeeee 11111111 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) In most cases, an application does not need to override _V_k_A_p_p::_r_u_n() to control events. Instead, the application can do such things as: use standard X mechanisms to add event handlers; use one or more workproc's; maintain its own queue of all that it needs to do, and then dispatch that work in a single workproc; If the above are not sufficient, the next thing to look into is calling _r_u_n(_B_o_o_l_e_a_n(*_a_p_p_E_v_e_n_t_H_a_n_d_l_e_r)(_X_E_v_e_n_t &)). If an application really does need to override _r_u_n(), though, then the application must call _r_u_n__f_i_r_s_t() before the first event processing is done, and it must call one of the ViewKit event processing routines from the application's event loop. If it does not do those two things, it may not be compatible with a future release of ViewKit. An application can override _V_k_A_p_p::_r_u_n() to add application code that will be executed each time through the event loop. _r_u_n_O_n_e_E_v_e_n_t() will only return if there was an X11 event. Otherwise it will service any workproc's, and then block waiting for the next X11 event. Such an overridden event loop might look like the following: MyApp::run() { run_first(); for (;;) { <application code here> runOneEvent(); <application code here> } } If the application does not want to block in ViewKit when there are no X11 events, it can use the following event loop. Note that since _h_a_n_d_l_e_P_e_n_d_i_n_g_E_v_e_n_t_s() neither blocks nor calls any workproc's, the application must take care of both of those things. MyApp::run() { XEvent event; run_first(); for (;;) { <application code, if any here> handlePendingEvents(); <application code to handle any workproc's here> // Block until there are more events XtAppPeekEvent( appContext(), &event); } } PPPPaaaaggggeeee 11112222 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) Alternatively, the loop could call _h_a_n_d_l_e_O_n_e_P_e_n_d_i_n_g_E_v_e_n_t() if it needs to take control each time through the event loop. Demonstration program For a demonstration program illustrating the several ways to customize the event loop, see /_u_s_r/_s_h_a_r_e/_s_r_c/_V_i_e_w_K_i_t/_B_a_s_i_c/_r_u_n._c++. qqqquuuuiiiittttYYYYoooouuuurrrrsssseeeellllffff;;;; virtual void quitYourself(); Applications that wish to exit, but that wish to allow other parts of the applications to abort the shutdown should call _q_u_i_t_Y_o_u_r_s_e_l_f(). _Q_u_i_t_Y_o_u_r_s_e_l_f() loops through each top level VkSimpleWindow (or subclass) calling each window's _o_k_T_o_Q_u_i_t() method. The windows are queried in the reverse order in which they are created, except that the window designated as the main window is checked last. (See VkSimpleWindow for more information.) If any object's _o_k_T_o_Q_u_i_t() method returns FALSE, the shutdown is terminated. If the resource _q_u_i_t_M_o_d_e is set to aaaallllllll, then no action is taken unless all windows return TTTTRRRRUUUUEEEE. If they do, then all windows are deleted and the application is terminated. If the resource _q_u_i_t_M_o_d_e is not set to aaaallllllll, then any window that returns TTTTRRRRUUUUEEEE is deleted and any window that returns FFFFAAAALLLLSSSSEEEE is not deleted. tttteeeerrrrmmmmiiiinnnnaaaatttteeee virtual void terminate(int status = 0); _t_e_r_m_i_n_a_t_e() is called within the ViewKit when any fatal error occurs. Because _t_e_r_m_i_n_a_t_e() is a virtual function, it can be overloaded by derived class that need to perform some cleanup before exiting. Classes that override _t_e_r_m_i_n_a_t_e() should perform their clean up and call their base class's _t_e_r_m_i_n_a_t_e() method. This function is not meant for clean shutdowns, but is normally reserved for situations in which the termination cannot be stopped. You may also want to consider using the UNIX _a_t_e_x_i_t() facility (See atexit(3C)). _T_e_r_m_i_n_a_t_e() is called automatically when all windows have been deleted. Also see _q_u_i_t_Y_o_u_r_s_e_l_f(). hhhhaaaannnnddddlllleeeeRRRRaaaawwwwEEEEvvvveeeennnntttt virtual void handleRawEvent(XEvent *event); PPPPaaaaggggeeee 11113333 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) Some events do not have a type and are not dispatched by the Xt dispatch mechanism. These events include client messages and events registered for non-widgets (for example, a PropertyNotify on the root window). When such an event is received, VkApp calls the virtual function _h_a_n_d_l_e_R_a_w_E_v_e_n_t() for event loops the VkApp instance as well as for all VkSimpleWindow instances. sssseeeettttMMMMaaaaiiiinnnnWWWWiiiinnnnddddoooowwww void setMainWindow(VkSimpleWindow *win); Specify a subclass of VkSimpleWindow to be treated as the main window of the application. This window is used by default for centering dialogs that have not specified otherwise, and is also treated differently when the application is being shut down. See _q_u_i_t_Y_o_u_r_s_e_l_f(). rrrraaaaiiiisssseeee virtual void raise(); Raises all visible windows in the application. lllloooowwwweeeerrrr virtual void lower(); Lowers all visible windows in the application. iiiiccccoooonnnniiiiffffyyyy virtual void iconify(); Iconifies all visible windows in the application. ooooppppeeeennnn virtual void open(); Opens all iconified windows in the application. sssshhhhoooowwww virtual void show(); Make all hidden, non-iconified windows visible. hhhhiiiiddddeeee virtual void hide(); PPPPaaaaggggeeee 11114444 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) Remove all visible, non-iconified windows from the screen. ssssttttaaaarrrrttttuuuuppppIIIIccccoooonnnniiiiffffiiiieeeedddd void startupIconified(Boolean flag); If called before an application enters the event loop (_r_u_n()), this will cause the application to start in an iconified state. bbbbuuuussssyyyyCCCCuuuurrrrssssoooorrrr virtual Cursor busyCursor(); Returns the current busy cursor used by the application. nnnnoooorrrrmmmmaaaallllCCCCuuuurrrrssssoooorrrr virtual Cursor normalCursor(); Returns the current normal cursor used by the application. sssseeeettttNNNNoooorrrrmmmmaaaallllCCCCuuuurrrrssssoooorrrr void setNormalCursor(Cursor c); Sets the normal cursor used by the application. If the application is not busy, this cursor will be displayed in all windows. If the application is busy, this cursor will become visible when the application returns from its busy state. sssseeeettttBBBBuuuussssyyyyCCCCuuuurrrrssssoooorrrr void setBusyCursor(Cursor c); void setBusyCursor(VkCursorList *cl); Sets the busy cursor used by the application. If the application is busy, this cursor will be displayed in all windows immediately. If the application is not busy, this cursor will become visible when the application becomes busy. If a VkCursorList object is specified as the busy cursor, the application can support an animated cursor. The application will cycle through one cursor each time the application calls progressing(). By default, a initial VkCursorList is installed in all ViewKit applications. sssshhhhoooowwwwCCCCuuuurrrrssssoooorrrr void showCursor(Cursor c); PPPPaaaaggggeeee 11115555 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) This function temporarily displays a cursor in all windows. The cursor can be reset by calling this function with a NULL cursor argument. The cursor will also be reset if the program becomes busy or returns from a busy state. This function is intended for use only for briefly displaying a cursor. For more permanent cursors, use _s_e_t_N_o_r_m_a_l_C_u_r_s_o_r(), or _s_e_t_B_u_s_y_C_u_r_s_o_r(). bbbbuuuussssyyyy vvvveeeerrrryyyyBBBBuuuussssyyyy nnnnoooottttBBBBuuuussssyyyy virtual void busy(const char *msg = NULL, VkSimpleWindow *parent = NULL); virtual void veryBusy(const char *msg = NULL, VkSimpleWindow *parent = NULL); virtual void notBusy(); Applications that expect to be unable to process events for some length of time should call _b_u_s_y() when they enter the busy state and call _n_o_t_B_u_s_y() when the program is no longer busy. Calls can be nested, but there must be matching pairs of _b_u_s_y() and _n_o_t_B_u_s_y() calls. If no arguments are given to _b_u_s_y(), the application simply displays a busy cursor. The application also blocks out all input, to prevent any type-ahead problems that might occur. If an string is given as the first argument, a dialog is posted to display the string. The string is treated first as the name of a resource that indicates a message to be displayed. If no resource is found the string is used as the message itself. If a VkSimpleWindow (or subclass) is specified, the dialog will be posted over this window. (See VkBusyDialog and VkDialogManager for more details on dialog behavior). The _v_e_r_y_B_u_s_y() function is intended for use when the application expects to be busy for an extended period of time. In this release, _v_e_r_y_B_u_s_y() simply calls _b_u_s_y(). In future releases, _v_e_r_y_B_u_s_y() may take some more interesting or appropriate action. Calling _n_o_t_B_u_s_y() undoes the affect of the most recent call to _b_u_s_y(). If the number of _n_o_t_B_u_s_y() calls matches the number of _b_u_s_y() calls, the application restores the normal cursor, enables device input, and unposts any busy dialog currently being displayed. pppprrrrooooggggrrrreeeessssssssiiiinnnngggg void progressing(char *msg = NULL); If an application is busy, and has a VkCursorList object installed, this member function causes the next cursor in the list to be displayed. This function should be called periodically while an application is busy. If an option string is provided, the string is displayed in a busy dialog. PPPPaaaaggggeeee 11116666 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) sssseeeettttBBBBuuuussssyyyyDDDDiiiiaaaalllloooogggg void setBusyDialog(VkBusyDialog *d); By default, _b_u_s_y() displays a dialog using the VkBusyDialog class. (See VkBusyDialog(3X)). Applications that wish to alter this behavior can call _s_e_t_B_u_s_y_D_i_a_l_o_g() to display an alternate dialog. This dialog must be implemented using a subclass of VkDialogManager. Calling _s_e_t_B_u_s_y_D_i_a_l_o_g() with a NULL argument restores the default VkBusyDialog. (See also, VkInterruptDialog(3X)). Applications should call _s_e_t_B_u_s_y_D_i_a_l_o_g() only when the application is not busy. aaaappppppppCCCCoooonnnntttteeeexxxxtttt XtAppContext appContext() const; This access function returns the application context used by the application. nnnnaaaammmmeeee char *name() const; This access function returns the base name by which the application was invoked. ddddiiiissssppppllllaaaayyyy Display *display() const; Returns a pointer to the X Display structure associated with this application's connection to the X server. aaaarrrrggggvvvv(((()))) char **argv() const; Returns a pointer to the argv array supplied to this application, but with all recognized command line arguments removed. aaaarrrrggggvvvv char *argv(int index) const; Returns a specific entry in the argv array. aaaarrrrggggcccc int argc() const; PPPPaaaaggggeeee 11117777 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) Returns the number of command line arguments remaining after all recognized arguments have been removed. aaaapppppppplllliiiiccccaaaattttiiiioooonnnnCCCCllllaaaassssssssNNNNaaaammmmeeee char *applicationClassName() const; Returns the application class name. mmmmaaaaiiiinnnnWWWWiiiinnnnddddoooowwww VkSimpleWindow *mainWindow() const; Returns a pointer to the VkSimpleWindow (or subclass) object installed as the application's main window. sssseeeettttFFFFaaaallllllllbbbbaaaacccckkkkssss static void setFallbacks(char **fallbacks) Sets _f_a_l_l_b_a_c_k_s as the _s_p_e_c_i_f_i_c_a_t_i_o_n__l_i_s_t needed to call _X_t_A_p_p_S_e_t_F_a_l_l_b_a_c_k_R_e_s_o_u_r_c_e_s(_3_X). _s_e_t_F_a_l_l_b_a_c_k_s() must be called before the application constructs its _V_k_A_p_p object, because the _V_k_A_p_p constructor does call _X_t_A_p_p_S_e_t_F_a_l_l_b_a_c_k_R_e_s_o_u_r_c_e_s(_3_X), passing it the _s_p_e_c_i_f_i_c_a_t_i_o_n__l_i_s_t. sssshhhheeeellllllllGGGGeeeeoooommmmeeeettttrrrryyyy char *shellGeometry() const; Returns the geometry of the base shell of the application. Some windows may wish to use this size as their own. ssssttttaaaarrrrttttuuuuppppIIIIccccoooonnnniiiiffffiiiieeeedddd Boolean startupIconified() const; Calling this function before _r_u_n() is entered will cause all application windows to start up as icons. ccccllllaaaassssssssNNNNaaaammmmeeee virtual const char *className() const; Returns the class name of the VkApp (or subclass) instance being used. ****tttthhhheeeeAAAApppppppplllliiiiccccaaaattttiiiioooonnnn VkApp *theApplication; PPPPaaaaggggeeee 11118888 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) This pointer can be used to reference the single instance of VkApp (or subclass) that must exist in any ViewKit application. uuuusssseeeeOOOOvvvveeeerrrrllllaaaayyyyAAAAppppppppssss(((()))) static void useOverlayApps(const Boolean flag) Effectively, _u_s_e_O_v_e_r_l_a_y_A_p_p_s(_T_R_U_E) defaults the entire application into the deepest available overlay planes. The normal default for the (unrealized) VkApp shell is the normal planes. That sets the default for all of its descendants to be the normal planes also. _u_s_e_O_v_e_r_l_a_y_A_p_p_s(_T_R_U_E) sets the VkApp shell in the deepest available overlay planes, thus resetting the default planes for the entire application. hhhheeeellllppppIIIInnnniiiitttt(((()))) hhhheeeellllppppMMMMssssgggg(((()))) hhhheeeellllppppIIIInnnnddddeeeexxxxMMMMssssgggg(((()))) hhhheeeellllppppIIIInnnniiiittttCCCCaaaallllllllbbbbaaaacccckkkk hhhheeeellllppppMMMMssssggggCCCCaaaallllllllbbbbaaaacccckkkk hhhheeeellllppppIIIInnnnddddeeeexxxxMMMMssssggggCCCCaaaallllllllbbbbaaaacccckkkk uuuusssseeeeSSSSGGGGIIIIHHHHeeeellllpppp(((()))) ssssggggiiiiHHHHeeeellllppppIIIInnnniiiitttt(((()))) ssssggggiiiiHHHHeeeellllppppMMMMssssgggg(((()))) ssssggggiiiiHHHHeeeellllppppIIIInnnnddddeeeexxxxMMMMssssgggg(((()))) int helpInit(char *client, char *sep); int helpMsg(char *key, char *book, char *userData); int helpIndexMsg(char *key, char *book); static const char *const helpInitCallback; static const char *const helpMsgCallback; static const char *const helpIndexMsgCallback; void useSGIHelp(); static void sgiHelpInit(VkCallbackObject* caller, void* clientData, void* callData); static void sgiHelpMsg(VkCallbackObject* caller, void* clientData, void* callData); static void sgiHelpIndexMsg(VkCallbackObject* caller, void* clientData, void* callData); Historically, the way to provide help from a ViewKit application has been to link the application with a library that implemented the C functions _S_G_I_H_e_l_p_I_n_i_t(), _S_G_I_H_e_l_p_M_s_g(), and _S_G_I_H_e_l_p_I_n_d_e_x_M_s_g(). ViewKit and the application would call these functions in response to users' requests for help. PPPPaaaaggggeeee 11119999 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) Help can also be provided by adding callbacks to the _h_e_l_p_I_n_i_t_C_a_l_l_b_a_c_k, _h_e_l_p_M_s_g_C_a_l_l_b_a_c_k, and _h_e_l_p_I_n_d_e_x_M_s_g_C_a_l_l_b_a_c_k lists. Instead of calling the _S_G_I_H_e_l_p*() functions, ViewKit and the application call the VkApp methods _h_e_l_p_I_n_i_t(), _h_e_l_p_M_s_g(), and _h_e_l_p_I_n_d_e_x_M_s_g(). If there are no callbacks installed on the corresponding callback lists, the VkApp help methods call the corresponding _S_G_I_H_e_l_p*() methods so that old applications continue to work. If callbacks are installed, the callbacks are called instead. An application that provides help using the _s_g_i_h_e_l_p program can call the VkApp method _u_s_e_S_G_I_H_e_l_p(), which will install _s_g_i_H_e_l_p_I_n_i_t() on the _h_e_l_p_I_n_i_t_C_a_l_l_b_a_c_k list, _s_g_i_H_e_l_p_M_s_g() on the _h_e_l_p_M_s_g_C_a_l_l_b_a_c_k list, and _s_g_i_H_e_l_p_I_n_d_e_x_M_s_g() on the _h_e_l_p_I_n_d_e_x_M_s_g_C_a_l_l_b_a_c_k list. _s_g_i_H_e_l_p_I_n_i_t(), _s_g_i_H_e_l_p_M_s_g(), and _s_g_i_H_e_l_p_I_n_d_e_x_M_s_gx() interact with the _s_g_i_h_e_l_p program to provide the same help that applications used to get by linking with -_l_h_e_l_p_m_s_g. An application wishing to provide its own help mechanism can add its own callbacks to the callback lists. The _c_a_l_l_D_a_t_a arguments for the _h_e_l_p_I_n_i_t_C_a_l_l_b_a_c_k, _h_e_l_p_M_s_g_C_a_l_l_b_a_c_k, and _h_e_l_p_I_n_d_e_x_M_s_g_C_a_l_l_b_a_c_k lists are of type _V_k_A_p_p::_H_e_l_p_I_n_i_t_A_r_g_s*, _V_k_A_p_p::_H_e_l_p_M_s_g_A_r_g_s*, and _V_k_A_p_p::_H_e_l_p_I_n_d_e_x_M_s_g_A_r_g_s* respectively. After installing these callbacks, _h_e_l_p_I_n_i_t() will need to be called. PPPPRRRROOOOTTTTEEEECCCCTTTTEEEEDDDD PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY ppppaaaarrrrsssseeeeCCCCoooommmmmmmmaaaannnnddddLLLLiiiinnnneeee(((()))) int parseCommandLine(XrmOptionDescRec *opt, Cardinal num); This function can be called by subclasses to extract arguments from the command line. ____wwwwiiiinnnnLLLLiiiisssstttt VkComponentList _winList; This member can be accessed by derived classes that need to manipulate the application's top-level windows. See VkComponentList(3X). aaaafffftttteeeerrrrRRRReeeeaaaalllliiiizzzzeeeeHHHHooooooookkkk(((()))) virtual void afterRealizeHook(); Some applications need to perform certain actions only after the application's windows have been realized. Examples might include installing a colormap, or setting up properties on the application's windows. PPPPaaaaggggeeee 22220000 VVVVkkkkAAAApppppppp((((3333xxxx)))) VVVVkkkkAAAApppppppp((((3333xxxx)))) IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCoooommmmppppoooonnnneeeennnntttt installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(), setDefaultResources(), getResources(), manage(), unmanage(), baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm VVVVkkkkCCCCaaaallllllllbbbbaaaacccckkkkOOOObbbbjjjjeeeecccctttt callCallbacks(), addCallback(), removeCallback(), removeAllCallbacks() KKKKNNNNOOOOWWWWNNNN DDDDEEEERRRRIIIIVVVVEEEEDDDD CCCCLLLLAAAASSSSSSSSEEEESSSS VkMsgApp CCCCLLLLAAAASSSSSSSSEEEESSSS UUUUSSSSEEEEDDDD BBBBYYYY TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS VkComponent, VkComponentList, VkDialogManager, VkSimpleWindow KKKKNNNNOOOOWWWWNNNN CCCCLLLLAAAASSSSSSSSEEEESSSS TTTTHHHHAAAATTTT UUUUSSSSEEEE TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS VkApp, VkBackground, VkDialogManager, VkDoubleBuffer, VkFatalErrorDialog, VkGraph, VkHelpPane, VkInterruptDialog, VkMenuBar, VkMsgFacility, VkNode, VkPeriodic, VkPipe, VkResizer, VkSimpleWindow SSSSEEEEEEEE AAAALLLLSSSSOOOO VkComponent, VkDialogManager, VkMsgApp, VkSimpleWindow, VkWindow, VkCursorList _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF PPPPaaaaggggeeee 22221111